What shipped

• A reusable resolveStateId module in @wiseiodev/linear-core that maps a state reference (a UUID or a human name) to a stateId for a team, with an optional preferred-type fallback reserved for later slices.
• linear issues update ANN-1 --state "In Progress" now works with no --input required.
• --input '{"state":"In Progress"}' and --input '{"stateName":"In Progress"}' resolve to the right stateId.
• Resolution is scoped to the target issue's team (the issue is fetched to read its teamId); a raw stateId UUID still passes through unchanged.
• Unknown/ambiguous state names fail with a typed error listing the team's valid states as name (type); state/stateName keys are stripped before the payload reaches GraphQL.
• New listWorkflowStatesForTeam gateway method (server-side team filter) and a position field on WorkflowStateRecord.
• Agent-facing guidance shipped with the feature: a "Set Issue State By Name" + "Common Mistakes" section in the bundled linear-cli skill, a setter-guidance block in issues update --help, a README example, and concrete state-by-name hints in the issue-triage and cycle-planning skills.

Dependencies collected

Files changed

 .reports/issue-22-qa.md                            | 130 ++++++
 .reports/issue-22.html                             | 444 +++++++++++++++++++++
 README.md                                          |   1 +
 assets/skills/cycle-planning/SKILL.md              |   7 +
 assets/skills/issue-triage/SKILL.md                |   7 +
 assets/skills/linear-cli/SKILL.md                  |  37 ++
 packages/cli/src/commands/input.ts                 |   8 +
 packages/cli/src/commands/issue-state.ts           |  76 ++++
 packages/cli/src/commands/resource.ts              |  11 +-
 packages/cli/src/help/resource-help.ts             |  12 +-
 packages/cli/src/index.ts                          |  19 +-
 packages/cli/tests/issue-state.test.ts             | 155 +++++++
 packages/linear-core/src/entities/linear-gateway.ts |  11 +
 packages/linear-core/src/entities/models.ts        |   1 +
 packages/linear-core/src/entities/state-resolver.ts |  94 +++++
 packages/linear-core/src/index.ts                  |   1 +
 packages/linear-core/tests/state-resolver.test.ts  |  85 ++++
 packages/skills-catalog/tests/skills-catalog.test.ts |  19 +
 18 files changed, 1111 insertions(+), 7 deletions(-)

Tests added

• packages/linear-core/tests/state-resolver.test.ts — 8 Vitest cases (UUID passthrough, case-insensitive name match, team scoping, preferred-type fallback incl. position-less states, not-found, ambiguous).
• packages/cli/tests/issue-state.test.ts — 10 Vitest cases (--state flag, state/stateName keys, explicit stateId untouched, empty stateId no longer pre-empts, padded UUID short-circuit, precedence, no-state passthrough, unknown name error).
• packages/skills-catalog/tests/skills-catalog.test.ts — +1 case asserting the bundled skill documents state-by-name.

Quality gates

• Lint / format — pnpm check:write (biome)
• Typecheck — pnpm typecheck (turbo, 4 pkgs)
• Unit tests — pnpm test (linear-core 58, cli 60, skills-catalog 7)
• Build — pnpm build (turbo, 4 pkgs)
• E2E — no E2E suite in this repo (N/A)

Adversarial review

• Iterations: 2
• Critical / Major: 0 / 0
• Minor: 0
• Nitpick: 0
• Resolved or accepted findings:
  • Two round-1 "major" findings resolved by scope/PRD reasoning: (a) reusing the global --state as the setter on update is PRD-mandated ("no new flag required") — the update help now documents the setter usage; (b) issues bulk-update state-by-name is owned by sibling issue State-by-name on issues create + bulk-update #27 and is untouched/unregressed here.
  • Five minor/nitpick findings fixed in code: undefined position now sorts last in the type fallback; only a non-empty stateId pre-empts resolution; asString trims so padded UUIDs short-circuit; explanatory comments added for the UUID short-circuit and the 250-state page cap.
  • Round 2 confirmed all fixes correct, no regressions, zero remaining critical/major.

Self-QA

See QA fallback log for the per-acceptance-criterion verification trail (deterministic unit tests, a runtime demonstration against the built @wiseiodev/linear-core module, a CLI help smoke test, and the docs/hints surfaces verified via issues update --help). This is a terminal CLI / SDK change with no browser surface, so a Playwright video is not applicable.

Acceptance criteria

• issues update <id> --state "<name>" sets the issue to the matching state
• --input '{"stateName":"<name>"}' and --input '{"state":"<name>"}' resolve to a stateId
• --input '{"stateId":"<uuid>"}' continues to work unchanged
• Resolution is scoped to the target issue's team
• Unknown/ambiguous name errors with the team's valid state names listed
• state/stateName keys never reach GraphQL
• Resolver unit tests cover UUID passthrough, name match, type fallback, not-found, ambiguous
• issues update normalization is tested (flag + JSON-key paths, stateId untouched)
• Docs/help/hints updated for the new capability (skill, CLI help, README, sibling skills)

Commits

d50dd61 docs(cli): document state-by-name across help, skill, and README
7d9c140 chore(report): add work report for issue #22
2328090 feat(cli): resolve issue workflow state by name on issues update

Linear

Refs: #22